﻿<html>
	<head>
		<style type="text/css">
.heading
{
	color: #000080;
	font-family: Calibri;
}
		.small {
	font-size: xx-small;
}
		</style>
		<title>Microsoft.Samples.Data.eSqlBlast</title>
	</head>
	
	<body>
	<font face="Verdana, Tahoma, Arial" size="2">
		<h1 class="heading"><strong>Microsoft.Samples.Data.eSqlBlast</strong></h1>
		
		<br />
		<h2 class="heading">License</h2>
		<p>This Product is distributed under the Microsoft Public License (Ms-PL).</p>

		<h3 class="heading">Microsoft Public License (Ms-PL)</h3>
		<p><a href="http://www.microsoft.com/resources/sharedsource/licensingbasics/publiclicense.mspx">
		http://www.microsoft.com/resources/sharedsource/licensingbasics/publiclicense.mspx</a></p>
		<p class="small">Published: October 12, 2006</p>
  
		<p>This license governs use of the accompanying software. 
		If you use the software, you accept this license. 
		If you do not accept the license, do not use the software.</p>

		<h4 class="heading">1. Definitions</h4>
		<p>The terms “reproduce,” “reproduction,” “derivative works,” and “distribution” 
		have the same meaning here as under U.S. copyright law.</p>
		<p>A “contribution” is the original software, or any additions or changes to the software.</p>
		<p>A “contributor” is any person that distributes its contribution under this license.</p>
		<p>“Licensed patents” are a contributor’s patent claims that read directly on its contribution.</p>

		<h4 class="heading">2. Grant of Rights</h4>
		<p>(A) Copyright Grant- Subject to the terms of this license, including the license conditions 
		and limitations in section 3, each contributor grants you a non-exclusive, worldwide, royalty-free 
		copyright license to reproduce its contribution, prepare derivative works of its contribution, 
		and distribute its contribution or any derivative works that you create.</p>
		<p>(B) Patent Grant- Subject to the terms of this license, including the license conditions and 
		limitations in section 3, each contributor grants you a non-exclusive, worldwide, royalty-free license 
		under its licensed patents to make, have made, use, sell, offer for sale, import, and/or otherwise 
		dispose of its contribution in the software or derivative works of the contribution in the software.</p>

		<h4 class="heading">3. Conditions and Limitations</h4>
		<p>(A) No Trademark License- This license does not grant you rights to use 
		any contributors’ name, logo, or trademarks.</p>
		<p>(B) If you bring a patent claim against any contributor over patents that you 
		claim are infringed by the software, your patent license from such contributor to 
		the software ends automatically.</p>
		<p>(C) If you distribute any portion of the software, you must retain all copyright, patent, 
		trademark, and attribution notices that are present in the software.</p>
		<p>(D) If you distribute any portion of the software in source code form, 
		you may do so only under this license by including a complete copy of this license 
		with your distribution. If you distribute any portion of the software in compiled 
		or object code form, you may only do so under a license that complies with this license.</p>
		<p>(E) The software is licensed “as-is.” You bear the risk of using it. The contributors 
		give no express warranties, guarantees or conditions. You may have additional consumer 
		rights under your local laws which this license cannot change. To the extent permitted 
		under your local laws, the contributors exclude the implied warranties of merchantability, 
		fitness for a particular purpose and non-infringement.</p>
		
		<br />
		<h2 class="heading">Author</h2>
		<p><strong>Zlatko Michailov</strong><br/>
		Program Manager, Microsoft Corp.<br>
		<a href="http://blogs.msdn.com/esql">http://blogs.msdn.com/esql</a> </p>
		
		<br />
		<h2 class="heading">Version</h2>
		<p>1.07.12.18</p>

		<br />
		<h2 class="heading">Overview</h2>
		<p>Microsoft.Samples.Data.eSqlBlast, briefly eSqlBlast, is a suite of 
		tools and libraries that complements Entity Framework. It aids 
		authoring, executing, and visualizing ad-hoc Entity SQL queries against 
		arbitrary EDM models. The tools of the eSqlBlast suite may be used 
		interactively, from the command line, or embedded in other programs. The 
		eSqlBlast suite also contains XSL transformation scripts for rendering 
		CSDL and its own raw XML format.</p>

		<br />
		<h2 class="heading">Architecture</h2>
		<p>eSqlBlast is a suite of five assemblies.</p>

		<h3 class="heading">Microsoft.Samples.Data.eSqlBlast.Language.dll</h3>
		<p>This is a general script processing library. It defines an interface 
		for declaring a language syntax, and implements a common script parser. 
		The language syntax is given in simple regex (regular expression) 
		grammar rules. Internally this assembly implements a mechanism that 
		builds a complex regex that matches statements of the given language 
		based on the simple grammar rules.</p>

		<h3 class="heading">Microsoft.Samples.Data.eSqlBlast.Core.dll</h3>
		<p>This is the only assembly that interacts with Entity Framework. Its 
		source code could be used as an example how to use the objects from the 
		System.Data.EntityClient namespace to connect to a model, execute an 
		Entity SQL query, and parse the returned EntityDataReader.</p>

		<h3 class="heading">Microsoft.Samples.Data.eSqlBlast.CmdShell.exe</h3>
		<p>This is a command-line executable built around the core DLL. It&#39;s 
		useful for invocation from batch scripts. It may optionally render 
		results into HTML.</p>

		<h3 class="heading">Microsoft.Samples.Data.eSqlBlast.WebShell</h3>
		<p>This is an ASP.NET web site that exposes the core functionality 
		against a predefined set of models. It includes three sample models, and 
		an XSL transformation for model rendering.</p>

 		<h3 class="heading">Microsoft.Samples.Data.eSqlBlast.WinShell.exe</h3>
		<p>This is an interactive standalone GUI executable that delivers the 
		best user experience. It can connect to an arbitrary EDM model and data 
		store as long as the interactive user has access. It includes the model 
		rendering XSL transformation. The query editor features color-coding and 
		intellisense. This tool can render results as HTML as well as raw XML. 
		It&#39;s designed for interactive ad-hoc Entity SQL query authoring.</p>

		<br />
		<h2 class="heading">User&#39;s Guide</h2>

		<h3 class="heading">Special Features</h3>
		<p>eSqlBlast implements some query elements that are not included in the Entity 
		Framework runtime:</p>
		<ul>
			<li><strong>Executing multiple queries</strong>. Queries must be 
			separated with &#39;;&#39;. Then each query is executed separately, i.e. if 
			a query fails the rest from the batch are still executed.</li>
			<li><strong>Block comments</strong>. /* */ are allowed at top-level 
			in the script. That way one or more whole queries may be excluded 
			from execution. Note: do not use block comments within a query since 
			the query is passed to Entity Framework without removing those 
			comments, and such a query will cause an exception. </li>
		</ul>

		<h3 class="heading">CmdShell</h3>
		<p>Launch options may be specified using either &#39;-&#39; or &#39;/&#39;. Most options 
		have a short name and a long name. Either style, or even mixing styles, 
		is equally acceptable. The following options are required:</p>
		<ul>
			<li><strong>-p[rovider] &quot;provider name&quot;</strong>, e.g. -provider &quot;System.Data.SqlClient&quot;</li>
			<li><strong>-m[etadata] &quot;list of metadata paths&quot;</strong>, e.g. -metadata &quot;C:\Model&quot;</li>
			<li><strong>-s[tring] &quot;provider connection string&quot;</strong>, e.g. -string 
			&quot;Server=.; Database=Northwind; Integrated Security=true;&quot;</li>
		</ul>
		<p>The following options are optional:</p>
		<ul>
			<li><strong>-i[nput] &quot;input file&quot;</strong>. If this option is 
			provided queries are read from the specified file. Otherwise, the 
			tool waits for a script from the standard input. That way this tool 
			may be piped.</li>
			<li><strong>-q[uery] &quot;query text&quot;</strong>. One or more queries may 
			be passed inline. This option may not be combined with -i. </li>
			<li><strong>-o[utput] &quot;output file&quot;</strong>. By default results are 
			sent to the standard output.</li>
			<li><strong>-t[ransform] &quot;XSL transformation script&quot;</strong>. By 
			default the default.xsl transformation is used, but the user is 
			allowed to specify their own.</li>
			<li><strong>-e[xception]</strong>. Enabling this option shows full 
			exception dumps. By default only the error message is shown.</li>
			<li><strong>-?</strong> or <strong>-h</strong>. Shows helpful 
			information.</li>
		</ul>
		
		<h3 class="heading">WebShell</h3>

		<h4 class="heading">Connection View</h4>
		<p>In this view the user chooses a model to connect to. The model is 
		automatically rendered. The connection string is also shown. To write queries, switch to the Query view.</p>

		<h4 class="heading">Query View</h4>
		<p>This is where queries are written. To execute a query, click the 
		Execute button. Checking the Full Exceptions check box enabled full exception dumps. By default 
		only error messages are shown.</p>

		<h4 class="heading">Results View</h4>
		<p>This is where results are rendered using the default XSL 
		transformation. Navigating to this view re-executes any text from the 
		Query view.</p>

		<h4 class="heading">Advanced View</h4>
		<p>This is a download page for the standalone executable, which allows 
		connecting to models outside the predefined set.</p>
		<p><strong>Note</strong>: The link to this view does not work in the Visual Studio Debugger.
		In order for it to work, first the WebShell project should be deployed, 
		and then the WinShell project should also be deployed.</p>


		<h3 class="heading">WinShell</h3>

		<h4 class="heading">Connection Tab</h4>
		<p>This is where an EntityConnection is interactively built. Each box 
		corresponds to a keyword of the entity connection string. When ready, 
		click the Connect button. The status bar shows the connectivity status.</p>

		<h4 class="heading">Model Tab</h4>
		<p>An arbitrary CSDL file may be rendered here. It is not necessary to 
		be connected to a model in order to render a CSDL.</p>

		<h4 class="heading">Query Tab</h4>
		<p>This is an editing environment for authoring Entity SQL queries. It 
		features color-coding and intellisense. Multiple queries may be written 
		and executed in a batch. Block comments at top-level are accepted, i.e. 
		whole queries may be included in block comments. To execute a script 
		click the Execute button, or the F5 key. Optionally choose to render raw 
		XML without any transformation, or choose to display full exception dumps 
		instead of only error messages. </p>

		<h4 class="heading">Results Tab</h4>
		<p>Shows results either as raw XML or after an XSL transformation. 
		Simply switching to this tab does not cause execution of the script from 
		the Query view.</p>

		<br />
		<h2 class="heading">Entity Framework Support</h2>
		<p>Visit the Entity Framework forum at:
		<a href="http://forums.microsoft.com/MSDN/ShowForum.aspx?ForumID=533&amp;SiteID=1">
		http://forums.microsoft.com/MSDN/ShowForum.aspx?ForumID=533&amp;SiteID=1</a> </p>

		<br />
		<p class="small">Copyright (c) 2006-2007 Microsoft Corp.</p>
	</font>
	</body>
</html>